.TH std::list::splice 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::list::splice \- std::list::splice

.SH Synopsis
   void splice( const_iterator pos, list& other );                    \fB(1)\fP
   void splice( const_iterator pos, list&& other );                   \fB(2)\fP \fI(since C++11)\fP
   void splice( const_iterator pos, list& other, const_iterator it ); \fB(3)\fP
   void splice( const_iterator pos, list&& other, const_iterator it   \fB(4)\fP \fI(since C++11)\fP
   );
   void splice( const_iterator pos, list& other,                      \fB(5)\fP
                const_iterator first, const_iterator last);
   void splice( const_iterator pos, list&& other,                     \fB(6)\fP \fI(since C++11)\fP
                const_iterator first, const_iterator last );

   Transfers elements from one list to another.

   No elements are copied or moved, only the internal pointers of the list nodes are
   re-pointed. No iterators or references become invalidated, the iterators to moved
   elements remain valid, but now refer into *this, not into other.

   1,2) Transfers all elements from other into *this. The elements are inserted before
   the element pointed to by pos. The container other becomes empty after the
   operation.
   3,4) Transfers the element pointed to by it from other into *this. The element is
   inserted before the element pointed to by pos.
   5,6) Transfers the elements in the range [first, last) from other into *this. The
   elements are inserted before the element pointed to by pos.

   The behavior is undefined if

     * get_allocator() != other.get_allocator(),
     * for overloads (1,2), *this and other refer to the same object,
     * for overloads (3,4), it is not a dereferenceable iterator into other, or
     * for overloads (5,6),

     * [first, last) is not a valid range in other, or
     * pos is in [first, last).

.SH Parameters

   pos         - element before which the content will be inserted
   other       - another container to transfer the content from
   it          - the element to transfer from other to *this
   first, last - the range of elements to transfer from other to *this

.SH Return value

   \fI(none)\fP

.SH Exceptions

   Throws nothing.

.SH Complexity

   1-4) Constant.
   5,6) Constant if other refers to the same object as *this, otherwise linear in
   std::distance(first, last).

.SH Example


// Run this code

 #include <iostream>
 #include <list>

 std::ostream& operator<<(std::ostream& ostr, const std::list<int>& list)
 {
     for (auto& i : list)
         ostr << ' ' << i;

     return ostr;
 }

 int main ()
 {
     std::list<int> list1{1, 2, 3, 4, 5};
     std::list<int> list2{10, 20, 30, 40, 50};

     auto it = list1.begin();
     std::advance(it, 2);

     list1.splice(it, list2);

     std::cout << "list1:" << list1 << '\\n';
     std::cout << "list2:" << list2 << '\\n';

     list2.splice(list2.begin(), list1, it, list1.end());

     std::cout << "list1:" << list1 << '\\n';
     std::cout << "list2:" << list2 << '\\n';
 }

.SH Output:

 list1: 1 2 10 20 30 40 50 3 4 5
 list2:
 list1: 1 2 10 20 30 40 50
 list2: 3 4 5

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to          Behavior as published               Correct behavior
                      references and iterators to the moved    they refer or point to
   LWG 250 C++98      element(s) were all invalidated          the
                                                               same element(s) in *this
   N2525   C++98      O(1) splicing could not be guaranteed if the behavior is
                      get_allocator() != other.get_allocator() undefined in this case

.SH See also

   merge     merges two sorted lists
             \fI(public member function)\fP
   remove    removes elements satisfying specific criteria
   remove_if \fI(public member function)\fP
